What would be the poetry workflow in read the docs? Pipfile support will be out soon btw. If this gets implemented, it would live as an option in the configuration file.

locally i run poetry install to create a virtualenv and install the dependencies, then poetry run sphinx-build ... to run sphinx-build inside that virtualenv.

although if there is a virtualenv already active then poetry will install the dependencies into that instead, which means it should work the same as for requirements.txt or Pipfile?

My workflow is pretty similar:

1. poetry install, which installs both dev and prod dependencies by default
2. cd docs, optional step
3. poetry run make html, to build the static website

Real project example that uses both poetry and rtd: https://github.com/wemake-services/wemake-django-template

So, replacing the pip install step by poetry install is all that's needed here or there are more tricks that I'm not seeing?

@humitos yes, I think so.

Mind, that we also have to work with venv differently: we need to prefix all commands with poetry run.

if you have the venv active, you can run poetry install and it will install into the current environment the same way that pip install -r requirements.txt will, you can then use the venv as you would had normally.

poetry run is just a shorthand to run things in the venv without having to remember where it is or activate it first.

dev and prod dependencies

Is there a use case where users only want to install dev/prod deps? There are any other configurations that users may want to set?

poetry install will install both dev and regular dependencies
poetry install --no-dev will install only regular dependencies and no dev stuff

the latter is more along the lines of setup.py install with the caveat that it wont install the module itself, i cant think of a reason off the top of my head not to install dev dependencies for docs generation...

you can also use poetry install --extras "foo bar" to install extra dependency groups foo and bar

full docs are at https://poetry.eustace.io/docs/cli/#install

I think this problem will resolve itself once the next version of pip is released with PEP-517 support (I've heard in January 2019?). It was merged - pypa/pip#5743
Then, a project only needs to add

[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"

to the pyproject.toml, and the normal pip install should work.

except the build script runs python setup.py install --force by default instead of a pip install . so pep-517 wont come into play?

@danielknell we do support installing the project using pip.

@uSpike I have read the pip issue and pep, but I wasn't able to understand it very well yet :/ will this replace pipenv too?

@stsewd pip might be able to install from a Pipfile at some point in the future, but AFAIK it is not on the road map any time soon.

@danielknell - yeah, check here: https://docs.readthedocs.io/en/latest/yaml-config.html#python-pip-install, might be able to do it through the web config too. So, guess we're just waiting on pypa/pip#6106. @stsewd : once pip 0.19.0 is out, how long before it makes it into a readthedocs image that we can use?

We install the latest version of pip before each build #4938, so it should be available after they release it :)

I'm not very familiar with Python virtual environments, but there may be another issue there.

I run poetry from a conf.py script, but get the following error, which I don't see how it could be fixed from user side:

Creating virtualenv clang-api-doc-py3.5 in /home/docs/.cache/pypoetry/virtualenvs
The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt-get install python3-venv

You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.

Failing command: ['/home/docs/.cache/pypoetry/virtualenvs/clang-api-doc-py3.5/bin/python', '-Im', 'ensurepip', '--upgrade', '--default-pip']

pypa/pip#6106 (comment)

Since new pip@19 is release, here's the short overview of what is going on.
I have locally checked how pip@19 works with two setups:

1. Application: https://github.com/wemake-services/wemake-django-template
2. Library: https://github.com/wemake-services/wemake-python-styleguide

Application

Trying: pip install .
Result:

    poetry.masonry.utils.module.ModuleOrPackageNotFound: No file/folder found for package wemake-django-template

    ----------------------------------------
Command "/Users/sobolev/Documents/github/wemake-django-template/.venv/bin/python3 /Users/sobolev/Documents/github/wemake-django-template/.venv/lib/python3.6/site-packages/pip/_vendor/pep517/_in_process.py prepare_metadata_for_build_wheel /var/folders/qn/2gssw9hx48g81chw0398hlrr0000gn/T/tmpbzmmkx48" failed with error code 1 in /private/var/folders/qn/2gssw9hx48g81chw0398hlrr0000gn/T/pip-req-build-2qbtac_8

Library

Trying: pip install .
Result: It installs everything as it should.

does it work within rtfd? i keep meaning to try but have not found time to update my projects yet with the config to install via pip.

@sobolevn I wouldn't expect https://github.com/wemake-services/wemake-django-template to install since it is a template (cookiecutter) project.

@uSpike poetry install works, so I had expected pip install to work as well.

poetry install will only install dev/prod dependencies, not the module itself
pip install . will try and install the module itself, and with it the prod dependencies.

the fact it does not install dev dependencies is concerning and maybe pep 517 isn't enough to fully support poetry projects?

poetry install also installs the project itself in the editable mode. https://github.com/sdispater/poetry/releases/tag/0.12.0

I have also tried to research this dev/no-dev problem, looks like there is no known solution yet.

that means poetry install is equivalent to pip install -e .

Can anyone try a project in rtd? We have the latest pip installed, let us know if there is anything else to do from our side to support poetry.

@sobolevn that project (https://github.com/wemake-services/wemake-django-template) is a template, you're not supposed to pip install it. The equivalent is having a requirements.txt, but they used poetry instead. The actual project is inside https://github.com/wemake-services/wemake-django-template/tree/master/%7B%7Bcookiecutter.project_name%7D%7D but you must run cookiecutter to make it.

@danielknell aah I forgot about that... there might be a way to pass flags to poetry via pip?

you may need to use this:

version: 2

build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  jobs:
    post_create_environment:
      # Install poetry
      # https://python-poetry.org/docs/#installing-manually
      - python -m pip install poetry
    post_install:
      # Install dependencies with 'docs' dependency group
      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs

sphinx:
  configuration: docs/conf.py